<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<!--
   Copyright 1999-2004 The Apache Software Foundation
 
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
 
       http://www.apache.org/licenses/LICENSE-2.0
 
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; I; SunOS 5.7 i86pc) [Netscape]">
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#0000FF" vlink="#FF0000" alink="#000088">

<h1>
Using the Java SecurityManager with Tomcat</h1>

<ul>
<li>
<a href="#why">Why use a SecurityManager?</a></li>

<li>
<a href="#requirements">System Requirements</a></li>

<li>
<a href="#precautions">Precautions</a></li>

<li>
<a href="#permissions">Types of Permissions</a></li>

<li>
<a href="#config">Configuring Tomcat for use with a SecurityManager</a></li>

<li>
<a href="#start">Starting Tomcat with a SecurityManager</a></li>

<li>
<a href="#violation">What happens when the SecurityManager detects a Security
violation?</a></li>

<li>
<a href="#trouble">Trouble shooting tomcat.policy configuration and Security
Violations</a></li>
</ul>

<h3>
<a NAME="why"></a>Why use a SecurityManager?</h3>
The Java SecurityManager is what allows a web browser to run an applet
in its own sandbox to prevent untrusted code from accessing files on the
local system, connecting to a host other than the one the applet was loaded
from, etc.
<p>In the same way the SecurityManager protects you from an untrusted applet
running in your browser, use of a SecurityManager while running Tomcat
can protect your server from trojan servlets, JSP's, JSP beans, and tag
libraries.&nbsp; Or even inadvertent mistakes.
<p>Imagine if someone who is authorized to publish JSP's on your site inadvertently
included the following in their JSP:
<blockquote>
<pre>&lt;% System.exit(1); %&gt;</pre>
</blockquote>

<p><br>Every time that JSP was executed by Tomcat, Tomcat would exit.
<p>Using the Java SecurityManager is just one more line of defense a system
administrator can use to keep the server secure and reliable.
<h3>
<a NAME="requirements"></a>System Requirements</h3>
Use of the SecurityManager requires a JVM that supports JDK 1.2.
<br>&nbsp;
<h3>
<a NAME="precautions"></a>Precautions</h3>
Implementation of a SecurityManager in Tomcat has not been fully tested
to ensure the security of Tomcat.&nbsp; No special Permissions have been
created to prevent access to internal Tomcat classes by JSP's, web applications,
servlets, beans, or tag libraries. Make sure that you are satisfied with
your SecurityManager configuration before allowing untrusted users to publish
web applications, JSP's, servlets, beans, or tag libraries.
<p>Still, running with a SecurityManager is definitely better than running
without one.
<br>&nbsp;
<h3>
<a NAME="permissions"></a>Types of Permissions</h3>
Permission classes are used to define what Permissions a class loaded by
Tomcat will have.&nbsp; There are a number of Permission classes as part
of the JDK and you can even create your own Permission class for use in
your own web applications.
<p>This is just a short summary of the System SecurityManager Permission
classes applicable to Tomcat.&nbsp; Please refer to the JDK documentation
for more information on using the below Permissions.
<p><b>java.util.PropertyPermission</b>
<br>&nbsp;&nbsp;&nbsp; Controls read/write access to JVM properties such
as java.home.
<p><b>java.lang.RuntimePermission</b>
<br>&nbsp;&nbsp;&nbsp; Controls use of some System/Runtime functions like
exit() and exec().
<p><b>java.io.FilePermission</b>
<br>&nbsp;&nbsp;&nbsp; Controls read/write/execute access to files and
directories.
<p><b>java.net.SocketPermission</b>
<br>&nbsp;&nbsp;&nbsp; Controls use of network sockets.
<p><b>java.net.NetPermission</b>
<br>&nbsp;&nbsp;&nbsp; Controls use of multicast network connections.
<p><b>java.lang.reflect.ReflectPermission</b>
<br>&nbsp;&nbsp;&nbsp; Controls use of reflection to do class introspection.
<p><b>java.security.SecurityPermission</b>
<br>&nbsp;&nbsp;&nbsp; Controls access to Security methods.
<p><b>java.security.AllPermission</b>
<br>&nbsp;&nbsp;&nbsp; Allows access to all permissions, just as if you
were running Tomcat without a SecurityManager.
<br>&nbsp;
<h3>
<a NAME="config"></a>Configuring Tomcat for use with a SecurityManager</h3>
<b>tomcat.policy</b>
<p>The security policies implemented by the Java SecurityManager are configured
in the <b>tomcat.policy </b>file located in the tomcat <code>conf</code> directory.&nbsp;
The tomcat.policy file replaces any system java.policy file.&nbsp; The
tomcat.policy file can be edited by hand or you can use the <b>policytool
</b>application
that comes with Java 1.2, or later.
<p>Entries in the tomcat.policy file use the standard java.policy file
format as follows:
<table border=0><tr><td><pre>// Example policy file entry

grant [signedBy &lt;signer&gt; [,codeBase &lt;code source&gt;] {
&nbsp;&nbsp;&nbsp; permission &lt;class&gt; [&lt;name&gt; [, &lt;action list&gt;]];
};
</td></tr></table></pre>
The <b>signedBy</b> and <b>codeBase </b>entries are optional when granting permissions.
Comment lines begin with // and end at a new line.
<p>The codeBase is in the form of a URL and for a file URL can use the
${java.home} and ${tomcat.home} properties which are expanded out to the
directory paths defined for them.
<p>Default tomcat.policy file
<table border=0><tr><td><pre>// Permissions for tomcat.

// javac needs this
grant codeBase "file:${java.home}/lib/-" {
&nbsp; permission java.security.AllPermission;
};

// Tomcat gets all permissions
grant codeBase "file:${tomcat.home}/lib/-" {
&nbsp; permission java.security.AllPermission;
};

grant codeBase "file:${tomcat.home}/classes/-" {
&nbsp; permission java.security.AllPermission;
};

// Example webapp policy
// By default we grant read access on webapp dir
// and read of the line.separator PropertyPermission
grant codeBase "file:${tomcat.home}/webapps/examples" {
&nbsp; permission java.net.SocketPermission "localhost:1024-","listen";
&nbsp; permission java.util.PropertyPermission "*","read";
};</td></tr></table></pre>

<p><br>Here is an example where in addition to the above, we want to grant
the examples web application the ability to connect to the localhost smtp
port so that it can send mail.
<table border=0><tr><td><pre>grant codeBase "file:${tomcat.home}/webapps/examples" {
&nbsp; permission java.net.SocketPermission "localhost:25","connect";
&nbsp; permission java.net.SocketPermission "localhost:1024","listen";
&nbsp; permission java.util.PropertyPermission "*","read";
};</td></tr></table></pre>
Now what if we wanted to give all contexts not configured by their own
grant entry some default permissions in addition to what Tomcat assigns
by default.
<table border=0><tr><td><pre>grant {
&nbsp; permission java.net.SocketPermission "localhost:1024","listen";
&nbsp; permission java.util.PropertyPermission "*","read";
};</td></tr></table></pre>
Finally, a more complex tomcat.policy file.&nbsp; In this case we are using
Tomcat as an app server for a number of remote web servers.&nbsp; We want
to limit what remote web servers can connect to Tomcat by using the Java
SecurityManager.
<br>&nbsp;
<table border=0><tr><td><pre>// Permissions for tomcat.
// javac needs this
grant codeBase "file:${java.home}/lib/-" {
&nbsp; permission java.security.AllPermission;
};

// Tomcat with IP filtering
grant codeBase "file:${tomcat.home}/lib/-" {
&nbsp; // Tomcat should be able to read/write all properties
&nbsp; permission java.util.PropertyPermission "*","read,write";
&nbsp; // Tomcat needs to be able to read files in its own directory
&nbsp; permission java.io.FilePermission "${tomcat.home}/-","read";
&nbsp; // Tomcat has to be able to write its logs
&nbsp; permission java.io.FilePermission "${tomcat.home}/logs/-","read,write";
&nbsp; // Tomcat has to be able to write to the conf directory
&nbsp; permission java.io.FilePermission "${tomcat.home}/conf/-","read,write";
&nbsp; // Tomcat has to be able to compile JSP's
&nbsp; permission java.io.FilePermission "${tomcat.home}/work/-","read,write,delete";
&nbsp; // Tomcat needs all the RuntimePermission's
&nbsp; permission java.lang.RuntimePermission "*";
&nbsp; // Needed so Tomcat can set security policy for a Context
&nbsp; permission java.security.SecurityPermission "*";
&nbsp; // Needed so that Tomcat will accept connections from a remote web server
&nbsp; // Replace XXX.XXX.XXX.XXX with the IP address of the remote web server
&nbsp; permission java.net.SocketPermission "XXX.XXX.XXX.XXX:1024-","accept,listen,resolve";
&nbsp; // Tomcat has to be able to use its port on the localhost
&nbsp; permission java.net.SocketPermission "localhost:1024-","connect,accept,listen,resolve";
};

// Example webapp policy
// By default we grant read access on webapp dir
// and read of the line.separator PropertyPermission
grant codeBase "file:${tomcat.home}/webapps/examples" {
&nbsp; permission java.net.SocketPermission "localhost:1024-","listen";
&nbsp; permission java.util.PropertyPermission "*","read";
};</td></tr></table></pre>

<h3>
<a NAME="start"></a>Starting Tomcat with a SecurityManager</h3>
Once you have configured the tomcat.policy for use
with a SecurityManager, Tomcat can be started with the SecurityManager
in place by adding the "-security" option to bin/startup.bat or bin/startup.
<br>&nbsp;
<h3>
<a NAME="violation"></a>What happens when the SecurityManager detects a
Security violation?</h3>
The JVM will throw an AccessControlException or a SecurityException when
the SecurityManager detects a security policy violation.
<br>&nbsp;
<h2>
<a NAME="trouble"></a>Trouble shooting tomcat.policy configuration and
Security Violations</h2>
You can turn on Java SecurityManager debug logging by setting the environmental
variable:
<pre>
    TOMCAT_OPTS=-Djava.security.debug=all
</pre>
The debug output will be written to Tomcat's log file, or the console if no log
file is defined.<br>
<br><strong>Note:</strong> This gives the most complete debugging information,
but generates many MB's of output, for less verbose security debug output, use:
<pre>
    TOMCAT_OPTS=-Djava.security.debug=access,failure
</pre>
Use the following shell command to determine all the security debug options
available: <tt>java -Djava.security.debug=help</tt><br>
<br>
<b>JSP Compile using JVM internal javac fails with AccessControlException
for RuntimePermission accessClassInPackage sun.tools.javac.</b>
<p>Check your JAVA_HOME/jre/lib/security/java.security file configuration.&nbsp;
Comment out the line "package.access=sun.".
<br>&nbsp;
<br>&nbsp;
</body>
</html>
